/*
 * Copyright (c) 2025 Huawei Technologies Co., Ltd.
 * openUBMC is licensed under Mulan PSL v2.
 * You can use this software according to the terms and conditions of the Mulan PSL v2.
 * You may obtain a copy of Mulan PSL v2 at:
 *         http://license.coscl.org.cn/MulanPSL2
 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
 * See the Mulan PSL v2 for more details.
 */

#ifndef MC_BUILTINS_STRING_H
#define MC_BUILTINS_STRING_H

#include <mc/array.h>
#include <string>
#include <string_view>
#include <vector>

namespace mcpy {

/**
 * @brief 字符串分割（按指定分隔符分割）
 * @param str 待分割字符串
 * @param sep 分隔符
 * @return 分割后的字符串列表
 */
MC_API mc::array<std::string> str_split(std::string_view str, std::string_view sep = " ");

// 字符串连接
MC_API std::string str_join(const std::vector<std::string>& v, std::string_view delim);
MC_API std::string str_join(const mc::array<std::string>& v, std::string_view delim);
/**
 * @brief 查找子串位置
 * @param str 待查找字符串
 * @param sub 子串
 * @return 子串位置索引，未找到返回 -1
 */
MC_API int str_find(std::string_view str, std::string_view sub);

/**
 * @brief 计数子串出现次数
 * @param str 待查找字符串
 * @param sub 子串
 * @return 子串出现次数
 */
MC_API int str_count(std::string_view str, std::string_view sub);

/**
 * @brief 查找子串位置，未找到抛出异常（类似 Python str.index）
 * @param str 待查找字符串
 * @param sub 子串
 * @return 子串位置索引
 * @throws mcpy::value_error 子串未找到时抛出
 */
MC_API int str_index(std::string_view str, std::string_view sub);

/**
 * @brief 判断是否全为数字字符
 * @param str 待判断字符串
 * @return true 全为数字，false 否则
 */
MC_API bool str_isdigit(std::string_view str);

/**
 * @brief 判断是否全为字母字符
 * @param str 待判断字符串
 * @return true 全为字母，false 否则
 */
MC_API bool str_isalpha(std::string_view str);

/**
 * @brief 首字母大写，其余小写
 * @param str 待转换字符串
 * @return 转换后的字符串
 */
MC_API std::string str_capitalize(std::string_view str);

/**
 * @brief 每个单词首字母大写
 * @param str 待转换字符串
 * @return 转换后的字符串
 */
MC_API std::string str_title(std::string_view str);

/**
 * @brief 数字字符串前补零
 * @param str 待补零字符串
 * @param width 目标宽度
 * @return 补零后的字符串
 */
MC_API std::string str_zfill(std::string_view str, int width);

} // namespace mcpy

#endif // MC_BUILTINS_STRING_H
